home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / timezone.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  22KB  |  512 lines
  1. /*
  2. ********************************************************************************
  3. *                                                                              *
  4. * COPYRIGHT:                                                                   *
  5. *   (C) Copyright Taligent, Inc.,  1997                                        *
  6. *   (C) Copyright International Business Machines Corporation,  1997-1999      *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.         *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure    *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  10. *                                                                              *
  11. ********************************************************************************
  12. *
  13. * File TIMEZONE.H
  14. *
  15. * Modification History:
  16. *
  17. *   Date        Name        Description
  18. *   04/21/97    aliu        Overhauled header.
  19. *   07/09/97    helena      Changed createInstance to createDefault.
  20. *   08/06/97    aliu        Removed dependency on internal header for Hashtable.
  21. *    08/10/98    stephen        Changed getDisplayName() API conventions to match
  22. *    08/19/98    stephen        Changed createTimeZone() to never return 0
  23. *    09/02/98    stephen        Sync to JDK 1.2 8/31
  24. *                             - Added getOffset(... monthlen ...)
  25. *                             - Added hasSameRules()
  26. *    09/15/98    stephen        Added getStaticClassID
  27. ********************************************************************************
  28. */
  29.  
  30. #ifndef TIMEZONE_H
  31. #define TIMEZONE_H
  32.  
  33.  
  34. #include "unistr.h"
  35. #include "locid.h"
  36.  
  37.  
  38.  
  39. class SimpleTimeZone;
  40.   
  41. /**
  42.  * <code>TimeZone</code> represents a time zone offset, and also figures out daylight
  43.  * savings.
  44.  *
  45.  * <p>
  46.  * Typically, you get a <code>TimeZone</code> using <code>createDefault</code>
  47.  * which creates a <code>TimeZone</code> based on the time zone where the program
  48.  * is running. For example, for a program running in Japan, <code>createDefault</code>
  49.  * creates a <code>TimeZone</code> object based on Japanese Standard Time.
  50.  *
  51.  * <p>
  52.  * You can also get a <code>TimeZone</code> using <code>createTimeZone</code> along
  53.  * with a time zone ID. For instance, the time zone ID for the Pacific
  54.  * Standard Time zone is "PST". So, you can get a PST <code>TimeZone</code> object
  55.  * with:
  56.  * <blockquote>
  57.  * <pre>
  58.  * TimeZone *tz = TimeZone::createTimeZone("PST");
  59.  * </pre>
  60.  * </blockquote>
  61.  * You can use <code>getAvailableIDs</code> method to iterate through
  62.  * all the supported time zone IDs. You can then choose a
  63.  * supported ID to get a <code>TimeZone</code>.
  64.  * If the time zone you want is not represented by one of the
  65.  * supported IDs, then you can create a custom time zone ID with
  66.  * the following syntax:
  67.  *
  68.  * <blockquote>
  69.  * <pre>
  70.  * GMT[+|-]hh[[:]mm]
  71.  * </pre>
  72.  * </blockquote>
  73.  *
  74.  * For example, you might specify GMT+14:00 as a custom
  75.  * time zone ID.  The <code>TimeZone</code> that is returned
  76.  * when you specify a custom time zone ID does not include
  77.  * daylight savings time.
  78.  *
  79.  
  80.   
  81.  * TimeZone is an abstract class representing a time zone.  A TimeZone is needed for
  82.  * Calendar to produce local time for a particular time zone.  A TimeZone comprises
  83.  * three basic pieces of information:<ul>
  84.  *    <li>A time zone offset; that, is the number of milliseconds to add or subtract
  85.  *      from a time expressed in terms of GMT to convert it to the same time in that
  86.  *      time zone (without taking daylight savings time into account).
  87.  *    <li>Logic necessary to take daylight savings time into account if daylight savings
  88.  *      time is observed in that time zone (e.g., the days and hours on which daylight
  89.  *      savings time begins and ends).
  90.  *    <li>An ID.  This is a text string that uniquely identifies the time zone.</ul>
  91.  *
  92.  * (Only the ID is actually implemented in TimeZone; subclasses of TimeZone may handle
  93.  * daylight savings time and GMT offset in different ways.  Currently we only have one
  94.  * TimeZone subclass: SimpleTimeZone.)
  95.  * <P>
  96.  * The TimeZone class contains a static list containing a TimeZone object for every
  97.  * combination of GMT offset and daylight-savings time rules currently in use in the
  98.  * world, each with a unique ID.  Each ID consists of a region (usually a continent or
  99.  * ocean) and a city in that region, separated by a slash, (for example, Pacific
  100.  * Standard Time is "America/Los_Angeles.")  Because older versions of this class used
  101.  * three- or four-letter abbreviations instead, there is also a table that maps the older
  102.  * abbreviations to the newer ones (for example, "PST" maps to "America/LosAngeles").
  103.  * Anywhere the API requires an ID, you can use either form.
  104.  * <P>
  105.  * To create a new TimeZone, you call the factory function TimeZone::createTimeZone()
  106.  * and pass it a time zone ID.  You can use the createAvailableIDs() function to
  107.  * obtain a list of all the time zone IDs recognized by createTimeZone().
  108.  * <P>
  109.  * You can also use TimeZone::createDefault() to create a TimeZone.  This function uses
  110.  * platform-specific APIs to produce a TimeZone for the time zone corresponding to 
  111.  * the client's computer's physical location.  For example, if you're in Japan (assuming
  112.  * your machine is set up correctly), TimeZone::createDefault() will return a TimeZone
  113.  * for Japanese Standard Time ("Asia/Tokyo").
  114.  */
  115. class U_I18N_API TimeZone {
  116. public:
  117.     virtual ~TimeZone();
  118.  
  119.     /**
  120.      * Creates a <code>TimeZone</code> for the given ID.
  121.      * @param ID the ID for a <code>TimeZone</code>, either an abbreviation such as
  122.      * "PST", a full name such as "America/Los_Angeles", or a custom ID
  123.      * such as "GMT-8:00".
  124.      * @return the specified <code>TimeZone</code>, or the GMT zone if the given ID
  125.      * cannot be understood.
  126.      */
  127.     static TimeZone* createTimeZone(const UnicodeString& ID);
  128.  
  129.     /**
  130.      * Returns a list of time zone IDs, one for each time zone with a given GMT offset.
  131.      * The return value is a list because there may be several times zones with the same
  132.      * GMT offset that differ in the way they handle daylight savings time.  For example,
  133.      * the state of Arizona doesn't observe Daylight Savings time.  So if you ask for
  134.      * the time zone IDs corresponding to GMT-7:00, you'll get back two time zone IDs:
  135.      * "America/Denver," which corresponds to Mountain Standard Time in the winter and
  136.      * Mountain Daylight Time in the summer, and "America/Phoenix", which corresponds to
  137.      * Mountain Standard Time year-round, even in the summer.
  138.      * <P>
  139.      * The caller owns the list that is returned, but does not own the strings contained
  140.      * in that list.  Delete the array, but DON'T delete the elements in the array.
  141.      *
  142.      * @param rawOffset  An offset from GMT in milliseconds.
  143.      * @param numIDs     Receives the number of items in the array that is returned.
  144.      * @return           An array of UnicodeString pointers, where each UnicodeString is
  145.      *                   a time zone ID for a time zone with the given GMT offset.  If
  146.      *                   there is no timezone that matches the GMT offset
  147.      *                   specified, NULL is returned.
  148.      */
  149.     static const UnicodeString** const createAvailableIDs(int32_t rawOffset, int32_t& numIDs);
  150.  
  151.     /**
  152.      * Returns a list of all time zone IDs supported by the TimeZone class (i.e., all
  153.      * IDs that it's legal to pass to createTimeZone()).  The caller owns the list that
  154.      * is returned, but does not own the strings contained in that list.  Delete the array,
  155.      * but DON'T delete the elements in the array.
  156.      *
  157.      * @param numIDs  Receives the number of zone IDs returned.
  158.      * @return        An array of UnicodeString pointers, where each is a time zone ID
  159.      *                supported by the TimeZone class.
  160.      */
  161.     static const UnicodeString** const createAvailableIDs(int32_t& numIDs);
  162.  
  163.     /**
  164.      * Creates a new copy of the default TimeZone for this host. Unless the default time
  165.      * zone has already been set using adoptDefault() or setDefault(), the default is
  166.      * determined by querying the system using methods in TPlatformUtilities. If the
  167.      * system routines fail, or if they specify a TimeZone or TimeZone offset which is not
  168.      * recognized, the TimeZone indicated by the ID kLastResortID is instantiated
  169.      * and made the default.
  170.      *
  171.      * @return   A default TimeZone. Clients are responsible for deleting the time zone
  172.      *           object returned.
  173.      */
  174.     static TimeZone* createDefault(void);
  175.  
  176.     /**
  177.      * Sets the default time zone (i.e., what's returned by getDefault()) to be the
  178.      * specified time zone.  If NULL is specified for the time zone, the default time
  179.      * zone is set to the default host time zone.  This call adopts the TimeZone object
  180.      * passed in; the clent is no longer responsible for deleting it.
  181.      *
  182.      * @param zone  A pointer to the new TimeZone object to use as the default.
  183.      */
  184.     static void adoptDefault(TimeZone* zone);
  185.  
  186.     /**
  187.      * Same as adoptDefault(), except that the TimeZone object passed in is NOT adopted;
  188.      * the caller remains responsible for deleting it.
  189.      *
  190.      * @param zone  The given timezone.
  191.      */
  192.     static void setDefault(const TimeZone& zone);
  193.  
  194.     /**
  195.      * Returns true if the two TimeZones are equal.  (The TimeZone version only compares
  196.      * IDs, but subclasses are expected to also compare the fields they add.)
  197.      *
  198.      * @param that  The TimeZone object to be compared with.
  199.      * @return      True if the given TimeZone is equal to this TimeZone; false
  200.      *              otherwise.
  201.      */
  202.     virtual bool_t operator==(const TimeZone& that) const;
  203.  
  204.     /**
  205.      * Returns true if the two TimeZones are NOT equal; that is, if operator==() returns
  206.      * false.
  207.      *
  208.      * @param that  The TimeZone object to be compared with.
  209.      * @return      True if the given TimeZone is not equal to this TimeZone; false
  210.      *              otherwise.
  211.      */
  212.     bool_t operator!=(const TimeZone& that) const {return !operator==(that);}
  213.  
  214.     /**
  215.      * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add
  216.      * to GMT to get local time in this time zone, taking daylight savings time into
  217.      * account) as of a particular reference date.  The reference date is used to determine
  218.      * whether daylight savings time is in effect and needs to be figured into the offset
  219.      * that is returned (in other words, what is the adjusted GMT offset in this time zone
  220.      * at this particular date and time?).  For the time zones produced by createTimeZone(),
  221.      * the reference data is specified according to the Gregorian calendar, and the date
  222.      * and time fields are in GMT, NOT local time.
  223.      *
  224.      * @param era        The reference date's era
  225.      * @param year       The reference date's year
  226.      * @param month      The reference date's month (0-based; 0 is January)
  227.      * @param day        The reference date's day-in-month (1-based)
  228.      * @param dayOfWeek  The reference date's day-of-week (1-based; 1 is Sunday)
  229.      * @param millis     The reference date's milliseconds in day, UTT (NOT local time).
  230.      * @return           The offset in milliseconds to add to GMT to get local time.
  231.      */
  232.     virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
  233.                               uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const = 0;
  234.  
  235.     // deprecated version
  236.     virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
  237.                               uint8_t dayOfWeek, int32_t millis) const = 0;
  238.  
  239.     /**
  240.      * Gets the time zone offset, for current date, modified in case of
  241.      * daylight savings. This is the offset to add *to* UTC to get local time.
  242.      * @param era the era of the given date.
  243.      * @param year the year in the given date.
  244.      * @param month the month in the given date.
  245.      * Month is 0-based. e.g., 0 for January.
  246.      * @param day the day-in-month of the given date.
  247.      * @param dayOfWeek the day-of-week of the given date.
  248.      * @param milliseconds the millis in day in <em>standard</em> local time.
  249.      * @param monthLength the length of the given month in days.
  250.      * @return the offset to add *to* GMT to get local time.
  251.      */
  252.     virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
  253.                            uint8_t dayOfWeek, int32_t milliseconds, 
  254.                            int32_t monthLength, UErrorCode& status) const = 0;
  255.  
  256.     /**
  257.      * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
  258.      * to GMT to get local time, before taking daylight savings time into account).
  259.      *
  260.      * @param offsetMillis  The new raw GMT offset for this time zone.
  261.      */
  262.     virtual void setRawOffset(int32_t offsetMillis) = 0;
  263.  
  264.     /**
  265.      * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
  266.      * to GMT to get local time, before taking daylight savings time into account).
  267.      *
  268.      * @return   The TimeZone's raw GMT offset.
  269.      */
  270.     virtual int32_t getRawOffset(void) const = 0;
  271.  
  272.     /**
  273.      * Fills in "ID" with the TimeZone's ID.
  274.      *
  275.      * @param ID  Receives this TimeZone's ID.
  276.      * @return    "ID"
  277.      */
  278.     UnicodeString& getID(UnicodeString& ID) const;
  279.  
  280.     /**
  281.      * Sets the TimeZone's ID to the specified value.  This doesn't affect any other
  282.      * fields (for example, if you say<
  283.      * blockquote><pre>
  284.      * .     TimeZone* foo = TimeZone::createTimeZone("America/New_York");
  285.      * .     foo.setID("America/Los_Angeles");
  286.      * </pre></blockquote>
  287.      * the time zone's GMT offset and daylight-savings rules don't change to those for
  288.      * Los Angeles.  They're still those for New York.  Only the ID has changed.)
  289.      *
  290.      * @param ID  The new timezone ID.
  291.      */
  292.     void setID(const UnicodeString& ID);
  293.  
  294.     /**
  295.      * Enum for use with getDisplayName
  296.      */
  297.  
  298.     enum EDisplayType { 
  299.         SHORT = 1,
  300.         LONG 
  301.     };
  302.  
  303.     /**
  304.      * Returns a name of this time zone suitable for presentation to the user
  305.      * in the default locale.
  306.      * This method returns the long name, not including daylight savings.
  307.      * If the display name is not available for the locale,
  308.      * then this method returns a string in the format
  309.      * <code>GMT[+-]hh:mm</code>.
  310.      * @return the human-readable name of this time zone in the default locale.
  311.      */
  312.     UnicodeString& getDisplayName(UnicodeString& result) const;
  313.  
  314.     /**
  315.      * Returns a name of this time zone suitable for presentation to the user
  316.      * in the specified locale.
  317.      * This method returns the long name, not including daylight savings.
  318.      * If the display name is not available for the locale,
  319.      * then this method returns a string in the format
  320.      * <code>GMT[+-]hh:mm</code>.
  321.      * @param locale the locale in which to supply the display name.
  322.      * @return the human-readable name of this time zone in the given locale
  323.      * or in the default locale if the given locale is not recognized.
  324.      */
  325.     UnicodeString& getDisplayName(const Locale& locale, UnicodeString& result) const;
  326.  
  327.     /**
  328.      * Returns a name of this time zone suitable for presentation to the user
  329.      * in the default locale.
  330.      * If the display name is not available for the locale,
  331.      * then this method returns a string in the format
  332.      * <code>GMT[+-]hh:mm</code>.
  333.      * @param daylight if true, return the daylight savings name.
  334.      * @param style either <code>LONG</code> or <code>SHORT</code>
  335.      * @return the human-readable name of this time zone in the default locale.
  336.      */
  337.     UnicodeString& getDisplayName(bool_t daylight, EDisplayType style, UnicodeString& result) const;
  338.  
  339.     /**
  340.      * Returns a name of this time zone suitable for presentation to the user
  341.      * in the specified locale.
  342.      * If the display name is not available for the locale,
  343.      * then this method returns a string in the format
  344.      * <code>GMT[+-]hh:mm</code>.
  345.      * @param daylight if true, return the daylight savings name.
  346.      * @param style either <code>LONG</code> or <code>SHORT</code>
  347.      * @param locale the locale in which to supply the display name.
  348.      * @return the human-readable name of this time zone in the given locale
  349.      * or in the default locale if the given locale is not recognized.
  350.      */
  351.     UnicodeString& getDisplayName(bool_t daylight, EDisplayType style, const Locale& locale, UnicodeString& result) const;
  352.  
  353.     /**
  354.      * Queries if this time zone uses daylight savings time.
  355.      * @return true if this time zone uses daylight savings time,
  356.      * false, otherwise.
  357.      */
  358.     virtual bool_t useDaylightTime(void) const = 0;
  359.  
  360.     /**
  361.      * Queries if the given date is in daylight savings time in
  362.      * this time zone.
  363.      * @param date the given UDate.
  364.      * @return true if the given date is in daylight savings time,
  365.      * false, otherwise.
  366.      */
  367.     virtual bool_t inDaylightTime(UDate date, UErrorCode& status) const = 0;
  368.  
  369.     /**
  370.      * Returns true if this zone has the same rule and offset as another zone.
  371.      * That is, if this zone differs only in ID, if at all.
  372.      * @param other the <code>TimeZone</code> object to be compared with
  373.      * @return true if the given zone is the same as this one,
  374.      * with the possible exception of the ID
  375.      */
  376.     virtual bool_t hasSameRules(const TimeZone& other) const;
  377.  
  378.     /**
  379.      * Clones TimeZone objects polymorphically. Clients are responsible for deleting
  380.      * the TimeZone object cloned.
  381.      *
  382.      * @return   A new copy of this TimeZone object.
  383.      */
  384.     virtual TimeZone* clone(void) const = 0;
  385.  
  386.     /**
  387.      * Return the class ID for this class.  This is useful only for
  388.      * comparing to a return value from getDynamicClassID().  For example:
  389.      * <pre>
  390.      * .   Base* polymorphic_pointer = createPolymorphicObject();
  391.      * .   if (polymorphic_pointer->getDynamicClassID() ==
  392.      * .       Derived::getStaticClassID()) ...
  393.      * </pre>
  394.      * @return The class ID for all objects of this class.
  395.      */
  396.     static UClassID getStaticClassID(void) { return (UClassID)&fgClassID; }
  397.  
  398.     /**
  399.      * Returns a unique class ID POLYMORPHICALLY. Pure virtual method. This method is to
  400.      * implement a simple version of RTTI, since not all C++ compilers support genuine
  401.      * RTTI. Polymorphic operator==() and clone() methods call this method.
  402.      * <P>
  403.      * Concrete subclasses of TimeZone must implement getDynamicClassID() and also a
  404.      * static method and data member:
  405.      * <pre>
  406.      * .     static UClassID getStaticClassID() { return (UClassID)&fgClassID; }
  407.      * .     static char fgClassID;
  408.      * </pre>
  409.      * @return   The class ID for this object. All objects of a given class have the
  410.      *           same class ID. Objects of other classes have different class IDs.
  411.      */
  412.     virtual UClassID getDynamicClassID(void) const = 0;
  413.  
  414. protected:
  415.  
  416.     /**
  417.      * Default constructor.  ID is initialized to the empty string.
  418.      */
  419.     TimeZone();
  420.  
  421.     /**
  422.      * Copy constructor.
  423.      */
  424.     TimeZone(const TimeZone& source);
  425.  
  426.     /**
  427.      * Default assignment operator.
  428.      */
  429.     TimeZone& operator=(const TimeZone& right);
  430.  
  431. private:
  432.     static char fgClassID;
  433.  
  434.     static TimeZone*        createCustomTimeZone(const UnicodeString&); // Creates a time zone based on the string.
  435.  
  436.     /**
  437.      * Convert a non-localized string to an integer using a system function. Return a
  438.      * failing UErrorCode status if all characters are not parsed.
  439.      */
  440. //  static int32_t          stringToInteger(const UnicodeString& string, UErrorCode& status);
  441.  
  442.     /**
  443.      * Delete function for fgHashtable.
  444.      */
  445.     static void             deleteTimeZone(void*);
  446.  
  447.     static int32_t          fTimezoneCount;
  448.     static UHashtable*       fgHashtable; // hash table of objects in kSystemTimeZones,
  449.                                          // maps zone ID to TimeZone object (lazy evaluated)
  450.     static TimeZone*        fgDefaultZone; // default time zone (lazy evaluated)
  451.     static UnicodeString*   fgAvailableIDs; // array containing all the IDs in kSystemTimeZones
  452.     static int32_t          fgAvailableIDsCount; // number of IDs in fgAvailableIDs
  453.     static UnicodeString    kLastResortID; // ID of time zone to use as default if we can't
  454.                                            // get a default from the system
  455.  
  456.  
  457.  
  458.     static const UnicodeString      GMT_ID;
  459.     static const int32_t            GMT_ID_LENGTH;
  460.     static const UnicodeString        CUSTOM_ID;
  461.  
  462.     static const TimeZone             *GMT;
  463.  
  464.    /**
  465.      * Return a reference to the static Hashtable of registered TimeZone
  466.      * objects.  Performs initialization if necessary.
  467.      * <P>
  468.      * This method is also responsible for initializing the array
  469.      * fgAvailableIDs and fgAvailableIDsCount.
  470.      */
  471.     static const UHashtable& getHashtable(void);
  472.  
  473.     /**
  474.      * Responsible for setting up fgDefaultZone.  Uses routines in TPlatformUtilities
  475.      * (i.e., platform-specific calls) to get the current system time zone.  Failing
  476.      * that, uses the platform-specific default time zone.  Failing that, uses the time
  477.      * zone specified by kLastResortID.
  478.      */
  479.     static void             initDefault(void);
  480.     static void             initSystemTimeZones(void); 
  481.  
  482.     static UErrorCode fgStatus;
  483.     static bool_t           kSystemInited;
  484.     static SimpleTimeZone*  kSystemTimeZones[]; // an array of TimeZone objects for
  485.                                                 // all possible time zones in
  486.                                                 // use around the world as of 1997.
  487.     static const int32_t    millisPerHour; // number of milliseconds in an hour
  488.  
  489.     UnicodeString           fID;    // this time zone's ID
  490. };
  491.  
  492.  
  493. // -------------------------------------
  494.  
  495. inline UnicodeString&
  496. TimeZone::getID(UnicodeString& ID) const
  497. {
  498.     ID = fID;
  499.     return ID;
  500. }
  501.  
  502. // -------------------------------------
  503.  
  504. inline void
  505. TimeZone::setID(const UnicodeString& ID)
  506. {
  507.     fID = ID;
  508. }
  509.  
  510. #endif //_TIMEZONE
  511. //eof
  512.